docs: explain client-side sampling callbacks

[He-wei-gui]

Summary

• add a Sampling docs page for the server-to-client sampling flow
• explain that clients opt in with sampling_callback and own the model/provider call
• document how model_preferences, include_context, and ClientRequestContext reach the callback
• add the page to the MkDocs navigation

This intentionally keeps the change provider-neutral and docs-only. It complements the existing server-side sampling snippet and avoids adding a full example project or model-provider dependency.

Addresses #1205.

Testing

• PYTHONIOENCODING=utf-8 uv run mkdocs build --strict

[pranjalbhatia710]

I was about to take a pass at #1205 and checked this PR first. This looks like it covers the missing client-side half of sampling clearly: it answers that the SDK does not call a provider directly, shows where sampling_callback plugs in, and explains that model_preferences / include_context are advisory inputs for the client rather than automatic behavior.

Local validation on current PR head:

uv run --frozen mkdocs build --strict

Result: docs build completed successfully. Only output was the existing MkDocs/Material compatibility warning, not specific to this change.

One small thing I specifically checked: adding sampling.md to mkdocs.yml makes the new page reachable from the docs nav, so this should directly address the discoverability gap from #1205.

[maxisbey]

Thanks for the PR. This has since landed via #2978. Closing as part of a general backlog cleanup following the v2 release. If this is still relevant against v2, feel free to reopen.

_{AI Disclaimer}