The header was meant to be deprecated for >1 year, but this was not documented.

Also adopt the

```
// IWYU pragma: always_keep // See pybind11/docs/type_caster_iwyu.rst
```

comment used in https://github.com/google/pywrapcc/pull/30073.

Currently pybind11/docs/type_caster_iwyu.rst only exists in google/pywrapcc#30073, but the intend is to upstream the changes (see PR description).

See also: https://clangd.llvm.org/design/include-cleaner

PiperOrigin-RevId: 578314470