add hive catalog table properties docs and refactor

[kevinjqliu]

Rationale for this change

Follow up to #2927
Add notes on updating iceberg table properties and hive table properties when using the hive catalog (HMS)
Minor refactor on variable naming to be more explicit

I added a test for the new edge case as well

Are these changes tested?

Are there any user-facing changes?

[Copilot]

Pull request overview

This pull request adds comprehensive documentation explaining the interaction between Iceberg table properties and HMS (Hive Metastore) table properties, along with a minor refactoring to improve variable naming clarity.

Changes:

• Added detailed documentation comments explaining how Iceberg and HMS properties are synchronized during table commits
• Refactored variable names to be more explicit (new_parameters → new_iceberg_properties, removed_keys → deleted_iceberg_properties, merged_params → existing_hms_parameters)
• Updated inline comments to better describe the merge operation

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[bharos]

Can we be more explicit here like
HMS-native properties (set outside Iceberg) cannot be deleted since they are not visible to Iceberg

because in cases like below, it can actually delete HMS properties?

# Set via Iceberg
table.updateProperties().set("hive.table_prop", "true").commit()
# → Goes to BOTH Iceberg metadata AND HMS
# → Now it's "visible" to Iceberg (tracked in Iceberg metadata)

# Unset via Iceberg
table.updateProperties().remove("hive.table_prop").commit()
# → deleted_iceberg_properties = {"hive.table_prop"}
# → Removed from BOTH Iceberg metadata AND HMS ✅

[kevinjqliu]

yea good point!

[Fokko]

Thanks for clarifying this @kevinjqliu 👍

[geruh]

LGTM thanks @kevinjqliu