docs(basics/controllers): clarify session variable usage, locking, best practices

[joshtrichards]

☑️ Resolves

This PR improves and clarifies the documentation for session handling and session variables for developers.

Completed while working on nextcloud/server#57794

Key updates:

• Clearly describes what sessions and session variables are for in web apps.
• Explains that Nextcloud uses PHP's native session mechanism enhanced with its own encryption and performance optimizations.
• Clarifies the distinction between the use of ISession and raw $_SESSION, warning against the latter.
• Documents the default on-demand locking behavior for session writes, including when (and why) the #[UseSession] attribute should be used for efficiency.
• Provides modern, practical, and safe code examples.
• Enumerates key methods of the ISession API and links directly to its definition.
• Adds more actionable warnings and notes on concurrency, race conditions, and locking for developers.

This brings the documentation fully in line with actual Nextcloud session implementation and gives app authors clear, accurate advice for robust and performant apps.

🖼️ Screenshots