cmake: replace PROJECT_SOURCE_DIR with ZEPHYR_BASE

Both variables were used (with the same value) interchangeably
throughout CMake files and per the discussion in GH issue,
ZEPHYR_BASE is preferred.

Also add a comment with explanation of one vs. the other.

Tested by building hello_world for several boards ensuring no errors.

Fixes #7173.

Signed-off-by: Alex Tereschenko <alext.mkrs@gmail.com>