Document step() action-scaling contract; add _validate_action_shares hook

[guitaristsam]

Problem

StockTradingEnv.step() rescales the input actions from [-1, 1] to integer share counts via actions = actions * self.hmax; actions.astype(int) before any _buy_stock/_sell_stock call sees it. This is correct behaviour, but subclasses overriding step() to add custom action constraints commonly:

1. Validate / round / clip the raw [-1, 1] action before the parent's * self.hmax rescaling. Net effect: the action grid collapses to {-hmax, 0, +hmax} with no fine-grained levels in between, and the policy std parameter gets stuck during PPO training (no gradient benefit to outputting fractional values).

2. Re-implement the entire step() flow to inject custom logic, which means the subclass has to re-track FinRL's internal state-layout conventions.

What this PR changes

Two non-breaking additions to env_stocktrading.py:

• Docstring on step() explicitly stating the [-1, 1] → integer-shares rescaling contract and pointing subclasses at the new hook.

• _validate_action_shares(action_shares) method, called after the rescaling and turbulence override but before the buy/sell loop. Default implementation is identity, so existing subclasses are unaffected. Subclasses that want post-rescaling constraints (per-step share-delta caps, integer-only enforcement, tighter budget pre-checks, no-shorting) can override this single method instead of re-implementing step().

Total: 43 lines added, 0 lines removed, no behaviour change for existing users.

Note on FinRL-X

I'm aware development is shifting to FinRL-X, which uses a weight-centric interface and has no Gym env. This PR targets legacy FinRL specifically because the action-scaling trap affects users following the existing educational/research tutorials, which explicitly remain on this repo.

Real-world reproducer

Hit this trap while subclassing StockTradingEnv to enforce integer-share trading on Indian equities. The smoking gun was the PPO std parameter stuck at 0.97 across 200k training timesteps. Full debugging diary, including 13 versions of single-variable iteration, at https://github.com/guitaristsam/RL_PPO_NIFTY50 — see the "Action scaling" section of CLAUDE.md.

[guitaristsam]

The failing pre-commit.ci check is not caused by this PR. Diagnostic:

• reorder-python-imports and black are reformatting 11 unrelated files (yahoodownloader.py, processor_yahoofinance.py, models.py, etc.) — none of which are touched by this PR. These appear to be drift since the last upstream pre-commit autofix.
• pyupgrade crashes with TypeError: cannot use a bytes pattern on a string-like object — this is an upstream pyupgrade incompatibility with Python 3.14 that pre-commit.ci is now using; completely independent of this change.
• flake8 is correctly skipped per ci: skip: [flake8].

I deliberately did not include the reformat of unrelated files in this PR to keep it focused on the action-scaling documentation and _validate_action_shares hook.

The patch itself (43 lines added, 0 removed) passes black, reorder-python-imports, and pyupgrade locally on the file alone.