include/kernel.h: Clean up documentation surrounding k_sched_lock() usage

Discussion in #55230 pointout out some areas that were unclear in the
existing docs.  Be more explicit about interactions between the
scheduler lock and scheduler behavior, and include a warning to maybe
start on the path to deprecating k_sched_lock().

Signed-off-by: Andy Ross <andyross@google.com>