[feat/precompile-tooling] docs: document the opt-in precompiled mode (#6138)

* docs: document the opt-in precompiled mode

Assisted-by: ClaudeCode:claude-fable-5

* chore: lint the -inl.h invariants of the precompiled mode

tools/check_inl_headers.py checks that each namespace-scope definition
in an -inl.h file has PYBIND11_INLINE, and that each macro in a
preprocessor condition is known: either the same for the library and
the module, or encoded in the precompiled config guard. Also document
that a custom PYBIND11_NAMESPACE must reach the library.

Assisted-by: ClaudeCode:claude-opus-5-5

* docs: note the call overhead of a non-LTO precompiled library

Release build, trivial bound functions, against an LTO header-only
module: AppleClang arm64 adds 2-4 ns per call (7-11%), GCC 15 Linux
aarch64 adds 1-2 ns (1-7%). With LTO on the library, both are within a
few percent.

Assisted-by: ClaudeCode:claude-opus-5-5