drivers: spi: improve API documentation

Enhance SPI API documentation.

The improvements include:
- Reorganize the doxygen into logical sections
- Add clear explanations of the CS behavior
- Improved descriptions of buffers and transfers
- Better descriptions of operational modes (master/slave)
- More clear explanation of clock polarity and phase configurations
- More clear explanation of SPI data word concepts and configurations

These changes make the API easier to understand for developers
implementing drivers or applications using the SPI interface.

Signed-off-by: Declan Snyder <declan.snyder@nxp.com>