[Parquet] ScanPlan docs: document the read-ahead buffering contract, and deprecate redundant ParquetPushDecoder APIs #11431

Follow-up to #10555.

1. Document what a read-ahead caller must implement. (review comment)

• How to avoid a copy. Without a row selection, the decoder requests a whole column chunk, and that chunk spans several planned ranges. A cache keyed by planned range must join those ranges for each request. A caller can instead fetch one buffer for each (row_group, column) and answer with Bytes::slice. This is zero-copy, and the decoder still releases the buffer, because the pushed range is the same as the requested range.
• When to drop cached ranges. The decoder requests each planned range at most one time for each visit to its row group. It never requests a range that a predicate prunes. Row groups can be read out of order or more than once. For this reason, eviction must follow the position in the plan, not the row_group number.

2. Deprecate APIs that ScanPlan makes redundant. (review)

ParquetPushDecoder::is_at_row_group_boundary and row_groups_remaining give information that a caller can now get from scan_plan(). Find out whether they have other users. If not, deprecate them and point users to ScanPlan.