feat(cli): deprecate version command in favor of --version flag (#3206)

Closes #3160

<!--
Thanks for opening a pull request!
-->

<!-- In the case this PR will resolve an issue, please replace
${GITHUB_ISSUE_ID} below with the actual Github issue id. -->
<!-- Closes #${GITHUB_ISSUE_ID} -->

# Rationale for this change

The `pyiceberg version` subcommand is non-standard. Most CLI tools use
`--version` instead.
This PR adds `--version` via Click's built-in `click.version_option()`
and deprecates the
old `version` subcommand with a visible warning message, following the
project's deprecation
conventions.

Note: I chose `removed_in="1.0.0"` to match the existing deprecation in
the REST catalog
(see `pyiceberg/catalog/rest/__init__.py`), but happy to adjust if a
different version is preferred.

## Are these changes tested?

Yes. Added two new tests:
- `test_version_flag` — verifies `pyiceberg --version` works correctly
- `test_version_command_emits_deprecation_warning` — verifies the old
command still works but emits a `DeprecationWarning` and prints a
visible deprecation notice to stderr

Updated the existing `test_version_does_not_load_catalog` to account for
the deprecation warning.
<img width="884" height="116" alt="Screenshot 2026-03-29 at 11 47 37 pm"
src="https://github.com/user-attachments/assets/cb4fe218-3671-41a3-83db-e90933271bb1"
/>

<img width="884" height="116" alt="Screenshot 2026-03-29 at 11 59 54 pm"
src="https://github.com/user-attachments/assets/10bafeaa-9bea-4d81-b7e1-0ec2abce571e"
/>


## Are there any user-facing changes?

Yes:
- `pyiceberg --version` is now available
- `pyiceberg version` still works but prints a deprecation warning
- Help text updated to reflect the deprecation
<!-- In the case of user-facing changes, please add the changelog label.
-->

---------

Co-authored-by: Kevin Liu <kevinjqliu@users.noreply.github.com>